<!DOCTYPE html>
<html lang="en">
  <head>
    <title>HTMLEntities  Reference</title>
    <link rel="stylesheet" type="text/css" href="css/jazzy.css" />
    <link rel="stylesheet" type="text/css" href="css/highlight.css" />
    <meta charset="utf-8">
    <script src="js/jquery.min.js" defer></script>
    <script src="js/jazzy.js" defer></script>
    
    <script src="js/lunr.min.js" defer></script>
    <script src="js/typeahead.jquery.js" defer></script>
    <script src="js/jazzy.search.js" defer></script>
  </head>
  <body>


    <a title="HTMLEntities  Reference"></a>

    <header class="header">
      <p class="header-col header-col--primary">
        <a class="header-link" href="index.html">
          HTMLEntities 4.0.0 Docs
        </a>
         (100% documented)
      </p>
    
      <p class="header-col--secondary">
        <form role="search" action="search.json">
          <input type="text" placeholder="Search documentation" data-typeahead>
        </form>
      </p>
    
        <p class="header-col header-col--secondary">
          <a class="header-link" href="https://github.com/Kitura/swift-html-entities">
            <img class="header-icon" src="img/gh.png"/>
            View on GitHub
          </a>
        </p>
    
    </header>

    <p class="breadcrumbs">
      <a class="breadcrumb" href="index.html">HTMLEntities Reference</a>
      <img class="carat" src="img/carat.png" />
      HTMLEntities  Reference
    </p>

    <div class="content-wrapper">
      <nav class="navigation">
        <ul class="nav-groups">
          <li class="nav-group-name">
            <a class="nav-group-name-link" href="Enums.html">Enumerations</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Enums/ParseError.html">ParseError</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a class="nav-group-name-link" href="Extensions.html">Extensions</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Extensions/String.html">String</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Extensions/String/HTMLEscapeOptions.html">– HTMLEscapeOptions</a>
              </li>
            </ul>
          </li>
        </ul>
      </nav>
      <article class="main-content">

        <section class="section">
          <div class="section-content top-matter">
            
            <h1 id='htmlentities' class='heading'>HTMLEntities</h1>

<p><a href="https://travis-ci.org/Kitura/swift-html-entities"><img src="https://api.travis-ci.org/Kitura/swift-html-entities.svg?branch=master" alt="Build Status - Master"></a>
<img src="https://img.shields.io/badge/os-macOS-green.svg?style=flat" alt="macOS">
<img src="https://img.shields.io/badge/os-linux-green.svg?style=flat" alt="Linux">
<img src="https://img.shields.io/badge/license-Apache2-blue.svg?style=flat" alt="Apache 2">
<a href="https://codecov.io/gh/Kitura/swift-html-entities"><img src="https://codecov.io/gh/Kitura/swift-html-entities/branch/master/graph/badge.svg" alt="codecov"></a>
<a href="https://github.com/Carthage/Carthage"><img src="https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat" alt="Carthage compatible"></a></p>
<h2 id='summary' class='heading'>Summary</h2>

<p>Pure Swift HTML encode/decode utility tool for Swift.</p>

<p>Includes support for HTML5 named character references. You can find the list of all 2231 HTML5 named character references <a href="https://www.w3.org/TR/html5/syntax.html#named-character-references">here</a>.</p>

<p><code>HTMLEntities</code> can escape ALL non-ASCII characters as well as the characters <code>&lt;</code>, <code>&gt;</code>, <code>&amp;</code>, <code>&quot;</code>, <code>’</code>, as these five characters are part of the HTML tag and HTML attribute syntaxes.</p>

<p>In addition, <code>HTMLEntities</code> can unescape encoded HTML text that contains decimal, hexadecimal, or HTML5 named character references.</p>
<h2 id='api-documentation' class='heading'>API Documentation</h2>

<p>API documentation for <code>HTMLEntities</code> is located <a href="https://kitura.github.io/swift-html-entities/">here</a>.</p>
<h2 id='features' class='heading'>Features</h2>

<ul>
<li>Supports HTML5 named character references (<code>NegativeMediumSpace;</code> etc.)</li>
<li>HTML5 spec-compliant; strict parse mode recognizes <a href="https://www.w3.org/TR/html5/syntax.html#tokenizing-character-references">parse errors</a></li>
<li>Supports decimal and hexadecimal escapes for all characters</li>
<li>Simple to use as functions are added by way of extending the default <code>String</code> class</li>
<li>Minimal dependencies; implementation is completely self-contained</li>
</ul>
<h2 id='version-info' class='heading'>Version Info</h2>

<p>Latest release of <code>HTMLEntities</code> requires Swift 4.0 and higher.</p>
<h2 id='installation' class='heading'>Installation</h2>
<h3 id='via-swift-package-manager' class='heading'>Via Swift Package Manager</h3>

<p>Add <code>HTMLEntities</code> to your <code>Package.swift</code>:</p>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">PackageDescription</span>

<span class="k">let</span> <span class="nv">package</span> <span class="o">=</span> <span class="kt">Package</span><span class="p">(</span>
  <span class="nv">name</span><span class="p">:</span> <span class="s">"&lt;package-name&gt;"</span><span class="p">,</span>
  <span class="o">...</span>
  <span class="nv">dependencies</span><span class="p">:</span> <span class="p">[</span>
    <span class="o">.</span><span class="nf">package</span><span class="p">(</span><span class="nv">url</span><span class="p">:</span> <span class="s">"https://github.com/Kitura/swift-html-entities.git"</span><span class="p">,</span> <span class="nv">from</span><span class="p">:</span> <span class="s">"3.0.0"</span><span class="p">)</span>
  <span class="p">]</span>
  <span class="c1">// Also, make sure to add HTMLEntities to your package target's dependencies</span>
<span class="p">)</span>
</code></pre>
<h3 id='via-cocoapods' class='heading'>Via CocoaPods</h3>

<p>Add <code>HTMLEntities</code> to your <code>Podfile</code>:</p>
<pre class="highlight plaintext"><code>target '&lt;project-name&gt;' do
  pod 'HTMLEntities', :git =&gt; 'https://github.com/Kitura/swift-html-entities.git'
end
</code></pre>
<h3 id='via-carthage' class='heading'>Via Carthage</h3>

<p>Add <code>HTMLEntities</code> to your <code>Cartfile</code>:</p>
<pre class="highlight plaintext"><code>github "Kitura/swift-html-entities"
</code></pre>
<h2 id='usage' class='heading'>Usage</h2>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">HTMLEntities</span>

<span class="c1">// encode example</span>
<span class="k">let</span> <span class="nv">html</span> <span class="o">=</span> <span class="s">"&lt;script&gt;alert(</span><span class="se">\"</span><span class="s">abc</span><span class="se">\"</span><span class="s">)&lt;/script&gt;"</span>

<span class="nf">print</span><span class="p">(</span><span class="n">html</span><span class="o">.</span><span class="nf">htmlEscape</span><span class="p">())</span>
<span class="c1">// Prints "&amp;#x3C;script&amp;#x3E;alert(&amp;#x22;abc&amp;#x22;)&amp;#x3C;/script&amp;#x3E;"</span>

<span class="c1">// decode example</span>
<span class="k">let</span> <span class="nv">htmlencoded</span> <span class="o">=</span> <span class="s">"&amp;lt;script&amp;gt;alert(&amp;quot;abc&amp;quot;)&amp;lt;/script&amp;gt;"</span>

<span class="nf">print</span><span class="p">(</span><span class="n">htmlencoded</span><span class="o">.</span><span class="nf">htmlUnescape</span><span class="p">())</span>
<span class="c1">// Prints "&lt;script&gt;alert(\"abc\")&lt;/script&gt;"</span>
</code></pre>
<h2 id='advanced-options' class='heading'>Advanced Options</h2>

<p><code>HTMLEntities</code> supports various options when escaping and unescaping HTML characters.</p>
<h3 id='escape-options' class='heading'>Escape Options</h3>
<h4 id='code-allowunsafesymbols-code' class='heading'><code>allowUnsafeSymbols</code></h4>

<p>Defaults to <code>false</code>. Specifies if unsafe ASCII characters should be skipped or not.</p>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">HTMLEntities</span>

<span class="k">let</span> <span class="nv">html</span> <span class="o">=</span> <span class="s">"&lt;p&gt;</span><span class="se">\"</span><span class="s">café</span><span class="se">\"</span><span class="s">&lt;/p&gt;"</span>

<span class="nf">print</span><span class="p">(</span><span class="n">html</span><span class="o">.</span><span class="nf">htmlEscape</span><span class="p">())</span>
<span class="c1">// Prints "&amp;#x3C;p&amp;#x3E;&amp;#x22;caf&amp;#xE9;&amp;#x22;&amp;#x3C;/p&amp;#x3E;"</span>

<span class="nf">print</span><span class="p">(</span><span class="n">html</span><span class="o">.</span><span class="nf">htmlEscape</span><span class="p">(</span><span class="nv">allowUnsafeSymbols</span><span class="p">:</span> <span class="kc">true</span><span class="p">))</span>
<span class="c1">// Prints "&lt;p&gt;\"caf&amp;#xE9;\"&lt;/p&gt;"</span>

</code></pre>
<h4 id='code-decimal-code' class='heading'><code>decimal</code></h4>

<p>Defaults to <code>false</code>. Specifies if decimal character escapes should be used instead of hexadecimal character escapes whenever numeric character escape is used (i.e., does not affect named character references escapes). The use of hexadecimal character escapes is recommended.</p>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">HTMLEntities</span>

<span class="k">let</span> <span class="nv">text</span> <span class="o">=</span> <span class="s">"한, 한, ế, ế, 🇺🇸"</span>

<span class="nf">print</span><span class="p">(</span><span class="n">text</span><span class="o">.</span><span class="nf">htmlEscape</span><span class="p">())</span>
<span class="c1">// Prints "&amp;#x1112;&amp;#x1161;&amp;#x11AB;, &amp;#xD55C;, &amp;#x1EBF;, e&amp;#x302;&amp;#x301;, &amp;#x1F1FA;&amp;#x1F1F8;"</span>

<span class="nf">print</span><span class="p">(</span><span class="n">text</span><span class="o">.</span><span class="nf">htmlEscape</span><span class="p">(</span><span class="nv">decimal</span><span class="p">:</span> <span class="kc">true</span><span class="p">))</span>
<span class="c1">// Prints "&amp;#4370;&amp;#4449;&amp;#4523;, &amp;#54620;, &amp;#7871;, e&amp;#770;&amp;#769;, &amp;#127482;&amp;#127480;"</span>
</code></pre>
<h4 id='code-encodeeverything-code' class='heading'><code>encodeEverything</code></h4>

<p>Defaults to <code>false</code>. Specifies if all characters should be escaped, even if some characters are safe. If <code>true</code>, overrides the setting for <code>allowUnsafeSymbols</code>.</p>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">HTMLEntities</span>

<span class="k">let</span> <span class="nv">text</span> <span class="o">=</span> <span class="s">"A quick brown fox jumps over the lazy dog"</span>

<span class="nf">print</span><span class="p">(</span><span class="n">text</span><span class="o">.</span><span class="nf">htmlEscape</span><span class="p">())</span>
<span class="c1">// Prints "A quick brown fox jumps over the lazy dog"</span>

<span class="nf">print</span><span class="p">(</span><span class="n">text</span><span class="o">.</span><span class="nf">htmlEscape</span><span class="p">(</span><span class="nv">encodeEverything</span><span class="p">:</span> <span class="kc">true</span><span class="p">))</span>
<span class="c1">// Prints "&amp;#x41;&amp;#x20;&amp;#x71;&amp;#x75;&amp;#x69;&amp;#x63;&amp;#x6B;&amp;#x20;&amp;#x62;&amp;#x72;&amp;#x6F;&amp;#x77;&amp;#x6E;&amp;#x20;&amp;#x66;&amp;#x6F;&amp;#x78;&amp;#x20;&amp;#x6A;&amp;#x75;&amp;#x6D;&amp;#x70;&amp;#x73;&amp;#x20;&amp;#x6F;&amp;#x76;&amp;#x65;&amp;#x72;&amp;#x20;&amp;#x74;&amp;#x68;&amp;#x65;&amp;#x20;&amp;#x6C;&amp;#x61;&amp;#x7A;&amp;#x79;&amp;#x20;&amp;#x64;&amp;#x6F;&amp;#x67;"</span>

<span class="c1">// `encodeEverything` overrides `allowUnsafeSymbols`</span>
<span class="nf">print</span><span class="p">(</span><span class="n">text</span><span class="o">.</span><span class="nf">htmlEscape</span><span class="p">(</span><span class="nv">allowUnsafeSymbols</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span> <span class="nv">encodeEverything</span><span class="p">:</span> <span class="kc">true</span><span class="p">))</span>
<span class="c1">// Prints "&amp;#x41;&amp;#x20;&amp;#x71;&amp;#x75;&amp;#x69;&amp;#x63;&amp;#x6B;&amp;#x20;&amp;#x62;&amp;#x72;&amp;#x6F;&amp;#x77;&amp;#x6E;&amp;#x20;&amp;#x66;&amp;#x6F;&amp;#x78;&amp;#x20;&amp;#x6A;&amp;#x75;&amp;#x6D;&amp;#x70;&amp;#x73;&amp;#x20;&amp;#x6F;&amp;#x76;&amp;#x65;&amp;#x72;&amp;#x20;&amp;#x74;&amp;#x68;&amp;#x65;&amp;#x20;&amp;#x6C;&amp;#x61;&amp;#x7A;&amp;#x79;&amp;#x20;&amp;#x64;&amp;#x6F;&amp;#x67;"</span>
</code></pre>
<h4 id='code-usenamedreferences-code' class='heading'><code>useNamedReferences</code></h4>

<p>Defaults to <code>false</code>. Specifies if named character references should be used whenever possible. Set to <code>false</code> to always use numeric character references, i.e., for compatibility with older browsers that do not recognize named character references.</p>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">HTMLEntities</span>

<span class="k">let</span> <span class="nv">html</span> <span class="o">=</span> <span class="s">"&lt;script&gt;alert(</span><span class="se">\"</span><span class="s">abc</span><span class="se">\"</span><span class="s">)&lt;/script&gt;"</span>

<span class="nf">print</span><span class="p">(</span><span class="n">html</span><span class="o">.</span><span class="nf">htmlEscape</span><span class="p">())</span>
<span class="c1">// Prints “&amp;#x3C;script&amp;#x3E;alert(&amp;#x22;abc&amp;#x22;)&amp;#x3C;/script&amp;#x3E;”</span>

<span class="nf">print</span><span class="p">(</span><span class="n">html</span><span class="o">.</span><span class="nf">htmlEscape</span><span class="p">(</span><span class="nv">useNamedReferences</span><span class="p">:</span> <span class="kc">true</span><span class="p">))</span>
<span class="c1">// Prints “&amp;lt;script&amp;gt;alert(&amp;quot;abc&amp;quot;)&amp;lt;/script&amp;gt;”</span>
</code></pre>
<h4 id='set-escape-options-globally' class='heading'>Set Escape Options Globally</h4>

<p>HTML escape options can be set globally so that you don&rsquo;t have to set them everytime you want to escape a string. The options are managed in the <code><a href="Extensions/String/HTMLEscapeOptions.html">String.HTMLEscapeOptions</a></code> struct.</p>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">HTMLEntities</span>

<span class="c1">// set `useNamedReferences` to `true` globally</span>
<span class="kt">String</span><span class="o">.</span><span class="kt">HTMLEscapeOptions</span><span class="o">.</span><span class="n">useNamedReferences</span> <span class="o">=</span> <span class="kc">true</span>

<span class="k">let</span> <span class="nv">html</span> <span class="o">=</span> <span class="s">"&lt;script&gt;alert(</span><span class="se">\"</span><span class="s">abc</span><span class="se">\"</span><span class="s">)&lt;/script&gt;"</span>

<span class="c1">// Now, the default behavior of `htmlEscape()` is to use named character references</span>
<span class="nf">print</span><span class="p">(</span><span class="n">html</span><span class="o">.</span><span class="nf">htmlEscape</span><span class="p">())</span>
<span class="c1">// Prints “&amp;lt;script&amp;gt;alert(&amp;quot;abc&amp;quot;)&amp;lt;/script&amp;gt;”</span>

<span class="c1">// And you can still go back to using numeric character references only</span>
<span class="nf">print</span><span class="p">(</span><span class="n">html</span><span class="o">.</span><span class="nf">htmlEscape</span><span class="p">(</span><span class="nv">useNamedReferences</span><span class="p">:</span> <span class="kc">false</span><span class="p">))</span>
<span class="c1">// Prints "&amp;#x3C;script&amp;#x3E;alert(&amp;#x22;abc&amp;#x22;)&amp;#x3C;/script&amp;#x3E;"</span>
</code></pre>
<h3 id='unescape-options' class='heading'>Unescape Options</h3>
<h4 id='code-strict-code' class='heading'><code>strict</code></h4>

<p>Defaults to <code>false</code>. Specifies if HTML5 parse errors should be thrown or simply passed over.</p>

<p><strong>Note</strong>: <code>htmlUnescape()</code> is a throwing function if <code>strict</code> is used in call argument (no matter if it is set to <code>true</code> or <code>false</code>); <code>htmlUnescape()</code> is NOT a throwing function if no argument is provided.</p>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">HTMLEntities</span>

<span class="k">let</span> <span class="nv">text</span> <span class="o">=</span> <span class="s">"&amp;#4370&amp;#4449&amp;#4523"</span>

<span class="nf">print</span><span class="p">(</span><span class="n">text</span><span class="o">.</span><span class="nf">htmlUnescape</span><span class="p">())</span>
<span class="c1">// Prints "한"</span>

<span class="nf">print</span><span class="p">(</span><span class="k">try</span> <span class="n">text</span><span class="o">.</span><span class="nf">htmlUnescape</span><span class="p">(</span><span class="nv">strict</span><span class="p">:</span> <span class="kc">true</span><span class="p">))</span>
<span class="c1">// Throws a `ParseError.MissingSemicolon` instance</span>

<span class="c1">// a throwing function because `strict` is passed in argument</span>
<span class="c1">// but no error is thrown because `strict: false`</span>
<span class="nf">print</span><span class="p">(</span><span class="k">try</span> <span class="n">text</span><span class="o">.</span><span class="nf">htmlUnescape</span><span class="p">(</span><span class="nv">strict</span><span class="p">:</span> <span class="kc">false</span><span class="p">))</span>
<span class="c1">// Prints "한"</span>
</code></pre>
<h2 id='acknowledgments' class='heading'>Acknowledgments</h2>

<p><code>HTMLEntities</code> was designed to support some of the same options as <a href="https://github.com/mathiasbynens/he"><code>he</code></a>, a popular Javascript HTML encoder/decoder.</p>
<h2 id='license' class='heading'>License</h2>

<p>Apache 2.0</p>

          </div>
        </section>


      </article>
    </div>
    <section class="footer">
      <p>&copy; 2021 <a class="link" href="https://github.com/Kitura/swift-html-entities" target="_blank" rel="external">IBM and the Kitura project authors</a>. All rights reserved. (Last updated: 2021-08-28)</p>
      <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.13.7</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external">Realm</a> project.</p>
    </section>
  </body>
</div>
</html>
